---
title: Migration Guide
---

# Migration Guide

## Migrating RainbowKit

### 2.x.x Breaking changes

The [wagmi](https://wagmi.sh) and [viem](https://viem.sh) peer dependencies have reached `2.x.x` with breaking changes.

Follow the steps below to migrate.

**1. Upgrade RainbowKit, `wagmi`, and `viem` to their latest versions**

```bash
npm i @rainbow-me/rainbowkit@2 wagmi@2 viem@2.x
```

**2. Install `@tanstack/react-query` peer dependency**

With Wagmi v2, [TanStack Query](https://tanstack.com/query/v5/docs/react/overview) is now a required peer dependency.

Install it with the following command:

```bash
npm i @tanstack/react-query
```

**3. Upgrade your RainbowKit and Wagmi configurations**

```diff
  import '@rainbow-me/rainbowkit/styles.css'

+ import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
- import { createPublicClient, http } from 'viem'
- import { WagmiConfig } from 'wagmi'
+ import { WagmiProvider, http } from 'wagmi'
- import { configureChains, createConfig } from 'wagmi'
  import { mainnet } from 'wagmi/chains'
  import { RainbowKitProvider } from '@rainbow-me/rainbowkit'
- import { getDefaultWallets, connectorsForWallets } from '@rainbow-me/rainbowkit'
+ import { getDefaultConfig } from '@rainbow-me/rainbowkit'

  /* getDefaultWallets is now optional */
- const { wallets } = getDefaultWallets({
-   appName: 'RainbowKit demo',
-   projectId: 'YOUR_PROJECT_ID',
-   chains,
- })

  /* connectorsForWallets is now optional */
- const connectors = connectorsForWallets([...wallets])

- const { chains, publicClient } = configureChains( 
-   [mainnet, sepolia], 
-   [publicProvider(), publicProvider()],
- )

- const config = createConfig({
-   autoConnect: true,
-   publicClient,
- })

  /* New API that includes Wagmi's createConfig and replaces getDefaultWallets and connectorsForWallets */
+ const config = getDefaultConfig({
+   appName: 'RainbowKit demo',
+   projectId: 'YOUR_PROJECT_ID',
+   chains: [mainnet],
+   transports: {
+     [mainnet.id]: http(),
+   },
+ })

+ const queryClient = new QueryClient()

  const App = () => {
    return (
-     <WagmiConfig config={config}>
+     <WagmiProvider config={config}>
+       <QueryClientProvider client={queryClient}>
-         <RainbowKitProvider chains={chains}>
+         <RainbowKitProvider>
            {/* Your App */}
          </RainbowKitProvider>
+       </QueryClientProvider>
-     </WagmiConfig>
+     </WagmiProvider>
    )
  }
```

**4. Check for breaking changes in `wagmi` and `viem`**

If you use `wagmi` hooks and `viem` actions in your dApp, you will need to follow the migration guides for v2:

- [Wagmi v2 Migration Guide](https://wagmi.sh/react/guides/migrate-from-v1-to-v2)
- [Viem v2 Breaking Changes](https://viem.sh/docs/migration-guide#2xx-breaking-changes)

#### RainbowKit Changes

**1. Improved behavior for EIP-6963 wallets**

Wallets that support the new EIP-6963 connection standard (including Rainbow, MetaMask, and more) will now automatically appear in an `Installed` section during the Connect Wallet experience. This ensures that users can always find their favorite wallets and connect to dApps without conflicts or fallback buttons.

Developers continue to have full control over the Custom Wallet List to emphasize preferred wallets for end users. It is encouraged that you continue to include the `injectedWallet` and `walletConnectWallet` in your list to supports all platforms.

**2. Wagmi configuration with getDefaultConfig**

This new API simplifies the configuration experience and replaces the need to use Wagmi's `createConfig` directly. Chain configuration is simplified, including inferred public providers for `transports`.

The default wallet list will be automatically included, deprecating the need to use `getDefaultWallets` and `connectorsForWallets`.

You can create a Custom Wallet List by passing imported or Custom Wallet connectors to `wallets`. Instantiating wallet connectors and passing `projectId` and `chains` is no longer required.

```
const config = getDefaultConfig({
  appName: 'RainbowKit demo',
  projectId: 'YOUR_PROJECT_ID',
  chains: [mainnet],
  wallets: [rainbowWallet], /* optional custom wallet list */
  /* Wagmi createConfig options including `transports` are also accepted */
})
```

**3. RainbowKitProvider**

You no longer need to pass `chains` to `<RainbowKitProvider>`.

```diff
- <RainbowKitProvider chains={chains}>
+ <RainbowKitProvider>
```

**4. Custom Chains**

The `Chain` type has changed in accordance with Wagmi v2, and continues to support RainbowKit's `iconUrl` and `iconBackground` metadata.

```diff
+ import { Chain } from '@rainbow-me/rainbowkit'

  const avalanche = {
    id: 43_114,
    name: 'Avalanche',
    iconUrl: 'https://s2.coinmarketcap.com/static/img/coins/64x64/5805.png',
    iconBackground: '#fff',
    nativeCurrency: { name: 'Avalanche', symbol: 'AVAX', decimals: 18 },
    rpcUrls: {
      default: { http: ['https://api.avax.network/ext/bc/C/rpc'] },
    },
    blockExplorers: {
      default: { name: 'SnowTrace', url: 'https://snowtrace.io' },
    },
    contracts: {
      multicall3: {
        address: '0xca11bde05977b3631167028862be2a173976ca11',
        blockCreated: 11_907_934,
      },
    },
  } as const satisfies Chain
```

Example with `getDefaultConfig`:

```diff
const config = getDefaultConfig({
+ chains: [
+   avalanche, /* custom chain */
+   {
+     ...mainnet,
+     iconBackground: '#000',
+     iconUrl: 'https://example.com/icons/ethereum.png',
+   }, /* metadata overides */
+ ],
});
```

Example with `createConfig`:

```diff
+ import { Chain } from '@rainbow-me/rainbowkit'
+ const chains: readonly [Chain, ...Chain[]] = [
+   {
+     ...mainnet,
+     iconBackground: '#000',
+     iconUrl: 'https://example.com/icons/ethereum.png',
+   },
+ ];
  const config = createConfig({
    chains,
    transports: {
      [mainnet.id]: http(),
    },
  })
```

**5. Custom Wallets**

RainbowKit wallet connectors have undergone substantial changes to support Wagmi v2. Reference the [updated docs](https://www.rainbowkit.com/docs/custom-wallets) and an [example connector](https://github.com/rainbow-me/rainbowkit/blob/main/packages/rainbowkit/src/wallets/walletConnectors/rainbowWallet/rainbowWallet.ts) to upgrade any Custom Wallet Connectors in your dApp.

Wallet connectors also now support the EIP-6963 standard with the `rdns` prop. Ensure that this is populated to prevent duplicate references to EIP-6963 supporting wallets in your wallet list.

### 1.x.x Breaking changes

#### Updated to wagmi v1

The [wagmi](https://wagmi.sh) peer dependency has been updated to `1.x.x`.

Follow the steps below to migrate.

**1. Upgrade RainbowKit and `wagmi` to their latest version**

```bash
npm i @rainbow-me/rainbowkit@^1 wagmi@^1
```

**2. Install `viem` peer dependency**

wagmi v1 requires the `viem` peer dependency. Install it with the following command:

```bash
npm i viem
```

**3. Ensure bundler and polyfill compatibility**

Reference our [Next.js Webpack Config](https://github.com/rainbow-me/rainbowkit/blob/main/examples/with-next/next.config.js) sample for configuration guidance for your project.

Additional framework guides for Vite and Remix are available [here](https://www.rainbowkit.com/docs/installation#additional-build-tooling-setup).

**4. Check for breaking changes in `wagmi`**

If you use `wagmi` hooks in your application, you will need to follow `wagmi`'s migration guide to v1.

[You can see their migration guide here](https://wagmi.sh/react/migration-guide).

### 0.12.x Breaking changes

The wagmi peer dependency has been updated to `0.12.x`.

RainbowKit has adopted the `WalletConnectLegacyConnector` connector in `wagmi` for continued WalletConnect v1 support. Support for WalletConnect v2 and `WalletConnectConnector` will soon be available as a patch release, without breaking changes.

Wallets will be transitioned automatically in future releases.

Every dApp must now provide a [WalletConnect Cloud](https://cloud.walletconnect.com/) `projectId` to enable WalletConnect v2. This must be completed before WalletConnect v1 bridge servers are shutdown on June 28, 2023. RainbowKit will quietly prefer v1 for all wallets if `projectId` is unspecified.

Follow the steps below to migrate.

#### 1. Upgrade RainbowKit and `wagmi` to their latest version

```bash
npm i @rainbow-me/rainbowkit@^0.12.0 wagmi@^0.12.0
```

#### 2. Supply a WalletConnect Cloud projectId

Every dApp that relies on WalletConnect now needs to obtain a `projectId` from [WalletConnect Cloud](https://cloud.walletconnect.com/). This is absolutely free and only takes a few minutes.

Provide the `projectId` to `getDefaultWallets` and individual RainbowKit wallet connectors like the following:

```ts
const projectId = 'YOUR_PROJECT_ID';

const { wallets } = getDefaultWallets({
  appName: 'My RainbowKit App',
  projectId,
  chains,
});

const connectors = connectorsForWallets([
  ...wallets,
  {
    groupName: 'Other',
    wallets: [
      readyWallet({ projectId, chains }),
      trustWallet({ projectId, chains }),
      ledgerWallet({ projectId, chains }),
    ],
  },
]);
```

### 0.11.x Breaking changes

The wagmi peer dependency has been updated to `0.11.x`.

Follow the steps below to migrate.

#### 1. Upgrade RainbowKit and `wagmi` to their latest version

```bash
npm i @rainbow-me/rainbowkit@^0.11.0 wagmi@^0.11.0
```

#### 2. Check for breaking changes in `wagmi`

If you use `wagmi` hooks in your application, you will need to check if your application has been affected by the breaking changes in `wagmi`.

[You can see their migration guide here](https://wagmi.sh/react/migration-guide#011x-breaking-changes).

### 0.10.x Breaking changes

The wagmi peer dependency has been updated to `0.10.x`.

Follow the steps below to migrate.

#### 1. Upgrade RainbowKit and `wagmi` to their latest version

```bash
npm i @rainbow-me/rainbowkit@^0.10.0 wagmi@^0.10.0
```

#### 2. Check for breaking changes in `wagmi`

If you use `wagmi` hooks in your application, you will need to check if your application has been affected by the breaking changes in `wagmi`.

[You can see their migration guide here](https://wagmi.sh/react/migration-guide#010x-breaking-changes).

### 0.9.x Breaking changes

The wagmi peer dependency has been updated to `0.9.x`.

Follow the steps below to migrate.

#### 1. Upgrade RainbowKit and `wagmi` to their latest version

```bash
npm i @rainbow-me/rainbowkit@^0.9.0 wagmi@^0.9.0
```

#### 2. Check for breaking changes in `wagmi`

If you use `wagmi` hooks in your application, you will need to check if your application has been affected by the breaking changes in `wagmi`.

[You can see their migration guide here](https://wagmi.sh/react/migration-guide#09x-breaking-changes).

### 0.8.x Breaking changes

The wagmi peer dependency has been updated to `0.8.x`.

Follow the steps below to migrate.

#### 1. Upgrade RainbowKit and `wagmi` to their latest version

```bash
npm i @rainbow-me/rainbowkit@^0.8.0 wagmi@^0.8.0
```

#### 2. Check for breaking changes in `wagmi`

If you use `wagmi` hooks in your application, you will need to check if your application has been affected by the breaking changes in `wagmi`.

[You can see their migration guide here](https://wagmi.sh/react/migration-guide#08x-breaking-changes).

### 0.7.x Breaking changes

If you're creating a custom wallet list, you must now import each wallet individually in order to reduce bundle size. Note that since wallets are no longer namespaced via the `wallet` object, all wallets now have a `Wallet` suffix.

```diff
-import { connectorsForWallets, wallet } from '@rainbow-me/rainbowkit';
+import { connectorsForWallets } from '@rainbow-me/rainbowkit';
+import {
+  injectedWallet,
+  rainbowWallet,
+  metaMaskWallet,
+  coinbaseWallet,
+  walletConnectWallet,
+} from '@rainbow-me/rainbowkit/wallets';

const wallets = [
-  wallet.injected({ chains }),
-  wallet.rainbow({ chains }),
-  wallet.metaMask({ chains }),
-  wallet.coinbase({ chains, appName: 'My App' }),
-  wallet.walletConnect({ chains }),
+  injectedWallet({ chains }),
+  rainbowWallet({ chains }),
+  metaMaskWallet({ chains }),
+  coinbaseWallet({ chains, appName: 'My App' }),
+  walletConnectWallet({ chains }),
];
```

Also note that the Steakwallet backwards compatibility layer has been removed. Omni should be used instead.

```diff
-import { wallet } from '@rainbow-me/rainbowkit';
+import { omniWallet } from '@rainbow-me/rainbowkit/wallets';

const wallets = [
-  wallet.steak({ chains }),
+  omniWallet({ chains }),
];
```

### 0.4.x Breaking changes

RainbowKit has updated the `wagmi` peer dependency to `0.5.x`.

Follow the steps below to migrate.

#### 1. Upgrade dependencies

Upgrade RainbowKit and wagmi to their latest version

```bash
npm i @rainbow-me/rainbowkit@^0.4.0 wagmi@^0.5.0
```

#### 2. Check for breaking changes in `wagmi`

If you use `wagmi` hooks in your application, you will need to check if your application has been affected by the breaking changes in `wagmi`.

[You can see their migration guide here](https://wagmi.sh/react/migration-guide#05x-breaking-changes).

### 0.3.x Breaking changes

Removed the `chainId` parameter from `createConnector` on the `Wallet` type.

**Note that all built-in wallets are using the new API. Most consumers will be unaffected. This change only affects consumers that have created/consumed [custom wallets](/docs/custom-wallets).**

If you previously derived RPC URLs from the `chainId` on `createConnector`, you can now remove that logic as `wagmi` now handles RPC URLs internally when used with `configureChains`.

```diff
import { connectorsForWallets, wallet, Chain, Wallet } from '@rainbow-me/rainbowkit';
import { chain, configureChains } from 'wagmi';
import { alchemyProvider } from 'wagmi/providers/alchemy';
import { publicProvider } from 'wagmi/providers/public';
import { WalletConnectConnector } from 'wagmi/connectors/walletConnect';

export interface MyWalletOptions {
  chains: Chain[];
}

-const chains = [chain.mainnet]
+const { chains } = configureChains(
+  [chain.mainnet],
+  [
+    alchemyProvider({ alchemyId: process.env.ALCHEMY_ID }),
+    publicProvider(),
+  ]
+);

export const rainbow = ({ chains }: MyWalletOptions): Wallet => ({
  ...
- createConnector: ({ chainId }) => {
+ createConnector: () => {
-   const rpc = chains.reduce(
-     (rpcUrlMap, chain) => ({
-       ...rpcUrlMap,
-       [chainId]: chain.rpcUrls.default,
-     }),
-     {}
-   );
    const connector = new WalletConnectConnector({
      chains,
      options: {
        qrcode: false,
-       rpc,
      },
    });
  }
  ...
}

const connectors = connectorsForWallets([
  {
    groupName: 'Recommended',
    wallets: [
      rainbow({ chains }),
    ],
  },
]);
```

### 0.2.x Breaking changes

RainbowKit has updated the `wagmi` peer dependency to `^0.4`.

Follow the steps below to migrate.

#### 1. Upgrade dependencies

Upgrade RainbowKit and wagmi to their latest version

```bash
npm i @rainbow-me/rainbowkit@^0.2.0 wagmi@^0.4.2
```

#### 2. Replace configureChains import

Import `configureChains` from wagmi instead of RainbowKit:

```diff
- import { configureChains } from '@rainbow-me/rainbowkit';
+ import { configureChains } from 'wagmi';
```

#### 3. Migrate providers

RainbowKit no longer exports an `apiProvider` API. Replace it with your desired provider from wagmi.

```diff
- import { apiProvider } from '@rainbow-me/rainbowkit';
```

#### Alchemy

Import `alchemyProvider` from `wagmi/providers/alchemy`.

```diff
+ import { alchemyProvider } from 'wagmi/providers/alchemy';

const { chains, provider } = configureChains(
  [chain.mainnet, chain.polygon, chain.optimism, chain.arbitrum],
- [apiProvider.alchemy(process.env.ALCHEMY_ID)]
+ [alchemyProvider({ alchemyId: process.env.ALCHEMY_ID })]
);
```

#### Infura

Import `infuraProvider` from `wagmi/providers/infura`.

```diff
+import { infuraProvider } from 'wagmi/providers/infura';

const { chains, provider } = configureChains(
  [chain.mainnet, chain.polygon, chain.optimism, chain.arbitrum],
- [apiProvider.infura(process.env.INFURA_ID)]
+ [infuraProvider({ infuraId: process.env.INFURA_ID })]
);
```

#### JSON RPC

Import `jsonRpcProvider` from `wagmi/providers/jsonRpc`.

```diff
+ import { jsonRpcProvider } from 'wagmi/providers/jsonRpc';

const { chains, provider } = configureChains(
  [chain.mainnet, chain.polygon],
  [
-   apiProvider.jsonRpc(chain => ({
-     rpcUrl: `https://${chain.id}.example.com`,
-   })),
+   jsonRpcProvider({
+     rpc: chain => ({
+       http: `https://${chain.id}.example.com`,
+     }),
+   }),
  ]
);
```

#### Public provider

Import `publicProvider` from `wagmi/providers/public`.

```diff
+ import { publicProvider } from 'wagmi/providers/public';

const { chains, provider } = configureChains(
  [chain.mainnet, chain.polygon],
- [apiProvider.fallback()]
+ [publicProvider()]
);
```

#### 4. Rename wagmi's provider

Rename `WagmiProvider` to `WagmiConfig`.

```diff
import {
- WagmiProvider
+ WagmiConfig
} from 'wagmi'

const App = () => {
  return (
-   <WagmiProvider client={wagmiClient}>...</WagmiProvider>
+   <WagmiConfig client={wagmiClient}>...</WagmiConfig>
  );
};
```

And you're done! 🌈
